home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / u_man / cat3 / Tk / preserve.z / preserve
Encoding:
Text File  |  1998-10-30  |  6.5 KB  |  133 lines
  1.  
  2.  
  3.  
  4. TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee((((3333TTTTkkkk))))                                              TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee((((3333TTTTkkkk))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Tk_Preserve, Tk_Release, Tk_EventuallyFree - avoid freeing storage while
  10.      it's being used
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
  14.  
  15.      TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee(_c_l_i_e_n_t_D_a_t_a)
  16.  
  17.      TTTTkkkk____RRRReeeelllleeeeaaaasssseeee(_c_l_i_e_n_t_D_a_t_a)
  18.  
  19.      TTTTkkkk____EEEEvvvveeeennnnttttuuuuaaaallllllllyyyyFFFFrrrreeeeeeee(_c_l_i_e_n_t_D_a_t_a, _f_r_e_e_P_r_o_c)
  20.  
  21. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  22.      ClientData    _c_l_i_e_n_t_D_a_t_a   (in)      Token describing structure to be
  23.                                           freed or reallocated.  Usually a
  24.                                           pointer to memory for structure.
  25.  
  26.      Tk_FreeProc   *_f_r_e_e_P_r_o_c    (in)      Procedure to invoke to free
  27.                                           _c_l_i_e_n_t_D_a_t_a.
  28.  
  29.  
  30. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  31.      These three procedures help implement a simple reference count mechanism
  32.      for managing storage.  They are designed to solve a problem having to do
  33.      with widget deletion.  When a widget is deleted, its widget record (the
  34.      structure holding information specific to the widget) must be returned to
  35.      the storage allocator.  However, it's possible that the widget record is
  36.      in active use by one of the procedures on the stack at the time of the
  37.      deletion.  This can happen, for example, if the command associated with a
  38.      button widget causes the button to be destroyed:  an X event causes an
  39.      event-handling C procedure in the button to be invoked, which in turn
  40.      causes the button's associated Tcl command to be executed, which in turn
  41.      causes the button to be deleted, which in turn causes the button's widget
  42.      record to be de-allocated.  Unfortunately, when the Tcl command returns,
  43.      the button's event-handling procedure will need to reference the button's
  44.      widget record.  Because of this, the widget record must not be freed as
  45.      part of the deletion, but must be retained until the event-handling
  46.      procedure has finished with it.  In other situations where the widget is
  47.      deleted, it may be possible to free the widget record immediately.
  48.  
  49.      TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee and TTTTkkkk____RRRReeeelllleeeeaaaasssseeee implement short-term reference counts for
  50.      their _c_l_i_e_n_t_D_a_t_a argument.  The _c_l_i_e_n_t_D_a_t_a argument identifies an object
  51.      and usually consists of the address of a structure.  The reference counts
  52.      guarantee that an object will not be freed until each call to TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee
  53.      for the object has been matched by calls to TTTTkkkk____RRRReeeelllleeeeaaaasssseeee.  There may be any
  54.      number of unmatched TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee calls in effect at once.
  55.  
  56.      TTTTkkkk____EEEEvvvveeeennnnttttuuuuaaaallllllllyyyyFFFFrrrreeeeeeee is invoked to free up its _c_l_i_e_n_t_D_a_t_a argument.  It
  57.      checks to see if there are unmatched TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee calls for the object.
  58.      If not, then TTTTkkkk____EEEEvvvveeeennnnttttuuuuaaaallllllllyyyyFFFFrrrreeeeeeee calls _f_r_e_e_P_r_o_c immediately.  Otherwise
  59.      TTTTkkkk____EEEEvvvveeeennnnttttuuuuaaaallllllllyyyyFFFFrrrreeeeeeee records the fact that _c_l_i_e_n_t_D_a_t_a needs eventually to be
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee((((3333TTTTkkkk))))                                              TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee((((3333TTTTkkkk))))
  71.  
  72.  
  73.  
  74.      freed.  When all calls to TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee have been matched with calls to
  75.      TTTTkkkk____RRRReeeelllleeeeaaaasssseeee then _f_r_e_e_P_r_o_c will be called by TTTTkkkk____RRRReeeelllleeeeaaaasssseeee to do the cleanup.
  76.  
  77.      All the work of freeing the object is carried out by _f_r_e_e_P_r_o_c.  _F_r_e_e_P_r_o_c
  78.      must have arguments and result that match the type TTTTkkkk____FFFFrrrreeeeeeeePPPPrrrroooocccc:
  79.           typedef void Tk_FreeProc(ClientData _c_l_i_e_n_t_D_a_t_a);
  80.      The _c_l_i_e_n_t_D_a_t_a argument to _f_r_e_e_P_r_o_c will be the same as the _c_l_i_e_n_t_D_a_t_a
  81.      argument to TTTTkkkk____EEEEvvvveeeennnnttttuuuuaaaallllllllyyyyFFFFrrrreeeeeeee.
  82.  
  83.      This mechanism can be used to solve the problem described above by
  84.      placing TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee and TTTTkkkk____RRRReeeelllleeeeaaaasssseeee calls around actions that may cause
  85.      undesired storage re-allocation.  The mechanism is intended only for
  86.      short-term use (i.e. while procedures are pending on the stack);  it will
  87.      not work efficiently as a mechanism for long-term reference counts.  The
  88.      implementation does not depend in any way on the internal structure of
  89.      the objects being freed;  it keeps the reference counts in a separate
  90.      structure.
  91.  
  92.  
  93. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  94.      free, reference count, storage
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.